package com.rcpcompany.ui.flows;

import org.eclipse.jface.dialogs.IDialogPage;
import org.eclipse.swt.layout.FillLayout;
import org.eclipse.swt.widgets.Composite;
import org.eclipse.ui.IWorkbenchPartSite;

/**
 * The interface of a single page in a {@link IFlowDirector}.
 * <p>
 * A page is meant to map parts of the model controlled by the
 * {@link IFlowDirector flow director} to SWT widgets. When changes are made in
 * the SWT widgets these are reflected in the interface.
 * <p>
 * The life-cycle is as follows:
 * <ul>
 * <li>{@link #initialize(IFlowDirector, IFlowContainer)} - invoked by the
 * container before the page is shown</li>
 * <li>{@link #createControl(Composite)} - invoked when the page is shown the
 * first time - if ever</li>
 * <li>{@link #refreshState()} - invoked just before the page is shown whenever
 * it is shown</li>
 * <li>{@link #saveState()} - invoked whenever the page is not shown any more</li>
 * <li>{@link #dispose()} - invoked when the director is disposed</li>
 * </ul>
 * {@link #refreshState()} and {@link #saveState()} can be invoked numerous
 * times!
 * <p>
 * Whenever a change is made to a page, {@link #pageUpdated()} must be invoked.
 * 
 * @noimplement Extend AbstractFlowPage
 * 
 * @author Tonny Madsen, The RCP Company
 */
public interface IFlowPage extends IDialogPage {

	/**
	 * Sets the context of this page.
	 * <p>
	 * Invoked by the container when the page is first returned by the director
	 * 
	 * @param director
	 *            the flow director
	 * @param container
	 *            the flow container
	 */
	public void initialize(IFlowDirector director, IFlowContainer container);

	/**
	 * Returns the flow director of the page.
	 * 
	 * @return the flow director
	 */
	public IFlowDirector getFlowDirector();

	/**
	 * Returns the flow container of the page.
	 * 
	 * @return the flow container
	 */
	public IFlowContainer getFlowContainer();

	/**
	 * Disposes this page.
	 * <p>
	 * Invoked whenever the page is disposed in the container of the director.
	 * This will happen when the director is closed.
	 * <p>
	 * {@link #saveState()} is always invoked before {@link #dispose()}.
	 */
	public void dispose();

	/**
	 * Refreshes the content of the page from the underlying model.
	 * <p>
	 * Invoked just before the page is shown to allow it to update the content
	 * of all SWT widgets based on any changes that might have been made in the
	 * model.
	 */
	public void refreshState();

	/**
	 * Saves the state of the page back into the underlying model.
	 * <p>
	 * Invoked when the page is not any more by the container of the director or
	 * the page is disposed.
	 */
	public void saveState();

	/**
	 * Creates the content of the page. Invoked when the page is shown the first
	 * time - if ever.
	 * <p>
	 * The given parent <code>Composite</code> will have a {@link FillLayout}
	 * and can have at most one child.
	 * 
	 * @param parent
	 *            the parent {@link Composite}
	 */
	public void createControl(Composite parent);

	/**
	 * Indicates that this page has been updated.
	 * <p>
	 * Shortcut for <code>getFlowContainer().pageUpdated(this)</code>.
	 */
	public void pageUpdated();

	/**
	 * Returns whether this page is the current one in the flow container.
	 * 
	 * @returns true if the page is active, and false otherwise
	 */
	public boolean isCurrentPage();

	/**
	 * Returns the site for this page. The site can be <code>null</code>.
	 * 
	 * @return the part site or <code>null</code>
	 */
	public IWorkbenchPartSite getSite();
}
